Device 网络状态#

Device 命名空间提供对当前设备硬件、系统环境、语言区域、屏幕信息、电池状态、方向感知、接近传感器以及网络接口等信息的访问能力，并提供相关状态变化的监听接口。

该 API 主要用于根据设备环境动态调整 UI、行为逻辑或系统能力使用方式。

#网络状态与变化监听

Device 是全局命名空间，无需导入；也可以使用 import { Device } from "scripting"，访问的是同一个对象。这三个方法用于主 App 中的活跃脚本。

import { Device, Dialog, Script } from "scripting"

const onChange = (state: Awaited<ReturnType<typeof Device.getNetworkState>>) => {
  console.log(state.status, state.interfaces, state.isExpensive, state.isConstrained)
}

try {
  const state = await Device.getNetworkState()
  console.log("系统初始网络路径：", state)
  Device.addNetworkChangeListener(onChange)
  await Dialog.alert({
    title: "网络监听",
    message: "切换 Wi-Fi 后返回，可在日志中查看变化。关闭此弹窗后结束监听。",
  })
} catch (error) {
  console.error(error)
} finally {
  Device.removeNetworkChangeListener(onChange)
  Script.exit()
}

快照字段：

getNetworkState() 等待真实系统路径回调，最多 10 秒；新建 monitor 不会伪造初始断网。监听异步发送初始快照，此后仅在公开字段变化时发送；同一函数重复注册会忽略。省略参数调用 removeNetworkChangeListener() 可移除当前 Device 对象的全部网络监听。脚本退出会清理监听和未完成查询；监听不会延长后台执行，也不保证挂起期间投递。

路径 satisfied 不代表 Internet、目标 TCP 服务、Bonjour 或 RSD 一定可达，应实际请求验证。接口不提供 SSID、蜂窝代际或飞行模式设置。原有 Device.networkInterfaces() 仍用于获取接口地址列表。

查询拒绝时可读取错误的 code：ERR_NETWORK_STATE_TIMEOUT（未收到首次系统事件）、ERR_NETWORK_STATE_LIMIT（超过 32 个待完成查询或 32 个不同监听）、ERR_PLATFORM_NOT_SUPPORTED（上下文不可用）、ERR_PRO_REQUIRED（访问被拒绝）。添加监听可能同步抛出适用的访问/数量错误和 ERR_INVALID_ARG_TYPE。移除始终可用于清理。访问被撤销后，下一次更新或调用会释放监听，不会把错误伪装成网络状态事件。

#Orientation

表示设备当前的物理朝向。

type Orientation =
  | "portrait"
  | "portraitUpsideDown"
  | "landscapeLeft"
  | "landscapeRight"
  | "faceUp"
  | "faceDown"
  | "unknown"

#说明

• portrait：竖屏，Home 键在下（或标准竖屏方向）
• portraitUpsideDown：竖屏倒置
• landscapeLeft：横屏，设备向左旋转
• landscapeRight：横屏，设备向右旋转
• faceUp：设备平放，屏幕朝上
• faceDown：设备平放，屏幕朝下
• unknown：无法确定方向

#InterfaceOrientation

表示App UI 的可旋转方向

type InterfaceOrientation =
  | "portrait"
  | "portraitUpsideDown"
  | "landscape"
  | "landscapeLeft"
  | "landscapeRight"
  | "all"
  | "allButUpsideDown"

#说明

• portrait：竖屏，Home 键在下（或标准竖屏方向）
• portraitUpsideDown：竖屏倒置
• landscape：横屏，设备向左旋转
• landscapeLeft：横屏，设备向左旋转
• landscapeRight：横屏，设备向右旋转
• all：所有可旋转方向
• allButUpsideDown：除了竖屏，所有可旋转方向

#NetworkInterface

描述单个网络接口地址的信息。

type NetworkInterface = {
  address: string
  netmask: string | null
  family: "IPv4" | "IPv6"
  mac: string | null
  isInternal: boolean
  cidr: string | null
}

#字段说明

• address：IP 地址
• netmask：子网掩码
• family：地址族，IPv4 或 IPv6
• mac：MAC 地址（部分系统或接口可能为 null）
• isInternal：是否为内部接口（如 loopback）
• cidr：CIDR 表示形式，例如 192.168.1.10/24

#BatteryState

表示当前电池状态。

type BatteryState = "full" | "charging" | "unplugged" | "unknown"

#说明

• full：电量已充满
• charging：正在充电
• unplugged：未连接电源
• unknown：无法确定状态

#Device Information

#model

const model: string

设备型号，例如 "iPhone"、"iPad"。

#localizedModel

const localizedModel: string

本地化后的设备型号名称。

#appVersion / appBuildNumber

同步只读字符串，用于识别 Scripting App，扩展中的脚本也可读取。appVersion 对应 CFBundleShortVersionString，appBuildNumber 对应 CFBundleVersion。构建号保持字符串（可能含小数点或前导零）。无法读取宿主 App 时使用当前运行 bundle；字段缺失时返回空字符串。

Device 是注入的全局 API，无需导入；也支持已有的导入别名：

import { Device } from "scripting"
console.log(`Scripting ${Device.appVersion} (${Device.appBuildNumber})`)
console.log(`OS ${Device.systemVersion}`)

这两个字段表示 Scripting 本体的版本，与脚本自身版本、操作系统版本分别独立，不需要权限或网络访问。

#systemVersion

const systemVersion: string

当前操作系统版本号，例如 "18.2"。

#systemName

const systemName: string

操作系统名称，例如 "iOS"、"iPadOS"、"macOS"。

#isiPad / isiPhone

const isiPad: boolean
const isiPhone: boolean

指示当前设备是否为 iPad 或 iPhone。

#screen

const screen: {
  width: number
  height: number
  scale: number
}

屏幕信息：

• width：屏幕宽度（逻辑像素）
• height：屏幕高度（逻辑像素）
• scale：屏幕缩放比例（如 2、3）

#Battery & Sensors

#batteryState

const batteryState: BatteryState

当前电池状态。

#batteryLevel

const batteryLevel: number

当前电量百分比，范围为 0.0 到 1.0。

#proximityState

const proximityState: boolean

接近传感器状态，true 表示设备靠近用户（例如通话时贴近耳朵）。

#Orientation & Layout

#isLandscape / isPortrait / isFlat

const isLandscape: boolean
const isPortrait: boolean
const isFlat: boolean

• isLandscape：是否处于横屏
• isPortrait：是否处于竖屏
• isFlat：设备是否平放（face up / face down）

#orientation

const orientation: Orientation

当前设备物理方向。

#supportedInterfaceOrientations

var supportedInterfaceOrientations: InterfaceOrientation[]

获取和设置当前支持的旋转方向。

#示例

function Page() {
  useEffect(() => {
    Device.supportedInterfaceOrientations = ["all"]
    return () => {
      Device.supportedInterfaceOrientations = Device.userConfiguredInterfaceOrientations
    }
  }, [])
  return <VStack>...</VStack>
}

#userConfiguredInterfaceOrientations

const userConfiguredInterfaceOrientations: InterfaceOrientation[]

获取用户配置的旋转方向。你可以使用这个值的来设置supportedInterfaceOrientations以恢复为默认的旋转方向。

#Appearance & Environment

#colorScheme

const colorScheme: ColorScheme

当前系统颜色模式，例如浅色或深色模式。

#isiOSAppOnMac

const isiOSAppOnMac: boolean

指示当前进程是否为运行在 macOS 上的 iPhone / iPad App（Mac Catalyst 或 iOS App on Mac）。

#Locale & Language

#systemLocale

const systemLocale: string

当前系统 Locale，例如 "en_US"。

#preferredLanguages

const preferredLanguages: string[]

用户偏好的语言列表，例如：

["en-US", "zh-Hans-CN"]

#systemLocales（已废弃）

const systemLocales: string[]

已废弃，请使用 preferredLanguages。

#systemLanguageTag

const systemLanguageTag: string

语言标签，例如 "en-US"。

#systemLanguageCode

const systemLanguageCode: string

语言代码，例如 "en"。

#systemCountryCode

const systemCountryCode: string | undefined

国家代码，例如 "US"。

#systemScriptCode

const systemScriptCode: string | undefined

书写系统代码，例如 "Hans"（简体中文）。

#Wake Lock

#isWakeLockEnabled

const isWakeLockEnabled: Promise<boolean>

查询当前是否启用了屏幕唤醒锁定（防止设备自动锁屏）。

#setWakeLockEnabled

function setWakeLockEnabled(enabled: boolean): void

启用或禁用 Wake Lock。

说明：

• 仅在 Scripting App 内可用
• 启用后可防止设备自动休眠

#Battery Listeners

#addBatteryStateListener

function addBatteryStateListener(
  callback: (state: BatteryState) => void
): void

监听电池状态变化。

#removeBatteryStateListener

function removeBatteryStateListener(
  callback?: (state: BatteryState) => void
): void

移除电池状态监听器。

• 未传入 callback 时将移除所有监听器

#addBatteryLevelListener

function addBatteryLevelListener(
  callback: (level: number) => void
): void

监听电量变化。

#removeBatteryLevelListener

function removeBatteryLevelListener(
  callback?: (level: number) => void
): void

移除电量监听器。

#Orientation Listeners

#addOrientationListener

function addOrientationListener(
  callback: (orientation: Orientation) => void
): void

开始监听设备方向变化。

注意事项：

• 必须先调用该方法才能接收方向变化
• 系统方向锁开启时不会生效

#removeOrientationListener

function removeOrientationListener(
  callback?: (orientation: Orientation) => void
): void

移除方向监听器。

• 未传入 callback 时将停止所有方向监听并结束观察

#Proximity Listeners

#addProximityStateListener

function addProximityStateListener(
  callback: (state: boolean) => void
): void

监听接近传感器状态变化。

#removeProximityStateListener

function removeProximityStateListener(
  callback?: (state: boolean) => void
): void

移除接近传感器监听器。

#Network

#networkInterfaces

function networkInterfaces(): Record<string, NetworkInterface[]>

获取当前设备的网络接口信息。

返回值说明：

• Key：接口名称（如 en0、lo0）
• Value：该接口对应的地址信息数组

适用于网络诊断、本地 IP 获取、调试用途。